/*
 *  disp.h
 *  StringSearch
 *
 *  Created by Mohammad H. Afrasiabi on 09-11-16.
 *  Copyright 2009 UBC. All rights reserved.
 *
 */

/*!
    @header		disp.h
    @abstract   String Dispatcher 
    @discussion Dispatcher is an evironment specially build for string processing especially string search.
				It provides a mechanism to disptch a text to mpi processors. 
				Each text is divided into overlapping chunks of text which would help different algorithms process them regardless of the original text.
				To simplify the work two blocks is provided (DISPATCH_INIT and DISPATCH_LOOP).
				As the names suggest Initialization of the buffer and algorithms should be done in DISPATCH_INIT block.
				DISPATCH_LOOP provides chunks of data on each iteration.
 
				Example:<br/><br/>
				
				DISPATCH_INIT(TEXT_BUFFER, RESULT_BUFFER, TEXT_SIZE, CHUNK_SIZE, OVERLAP_SIZE) <br/>
				{<br/>
				<p>init block<br/></p>
				}<br/>
				DISPATCH_LOOP(char * CHUNK_BUFFER)<br/>
				{<br/>
				<p>loop block<br/></p>
				}<br/>
				DISPATCH_END<br/>
*/


#pragma once

// Directives
//////////////

#ifndef ROOT
#define ROOT 0
#endif

#ifndef PARTIAL_RESULT_SIZE
#define PARTIAL_RESULT_SIZE 20
#endif

#define ITERATOR_END -1
#define ITERATOR_BEGIN 0

// Typedefs
////////////

typedef int Disp_Iterator_Type;


// Prototypes
//////////////


char * Disp_Get_Chunk(Disp_Iterator_Type iterator);

int Disp_Get_Chunk_Size();

/*!
	@function
	@abstract   Initialize the Dispatch execution environment
	@discussion Arguments from main() should be passed to this function for initialization purposes. Disp_Finalize() should be called to free up the resources allocated by this function
	@result     Return zero if sucessful
*/

int		Disp_Init(char	** textBuffer, 
				  int	textSize, 
				  int	chunkSize, 
				  int	overlapSize);


/*!
	@function
	@abstract   Gathers the result of each processor in the end.
	@discussion Gathers the result of each processor which is added by function Disp_Add_Result(). The result buffer in -1 terminated.
	@param      results Pointer to the result buffer.
*/
void	Disp_Gather(int **results);

/*!
	@function
	@abstract   Add result to the buffer
	@discussion Should be used to add to the result buffer. The function takes care of the relative position of the solution in the textBuffer.
	@param      index Index of the result
*/
void	Disp_Add_Result(int index);

/*!
	@function
	@abstract   Synchronize an integer variable
	@discussion Synchronize an integer variable among processors.
	@param      value Pointer to the interger variable.
*/
void	Disp_Sync_Int(int *value);

/*!
	@function
	@abstract   Synchronize a string variable
	@discussion Synchronize a string variable among processors.
	@param      string Pointer to the string variable.
	@param      size	Size of the string buffer.
 */
void	Disp_Sync_String(char *string, int size);

/*!
	@function
	@abstract   Prints the results in the consol.
	@discussion For debugging purposes, print the result buffer into the console.
	@param      results Pointer to the result buffer should be passed
*/
void	Disp_Print_Results(int *results);

Disp_Iterator_Type Disp_Get_Next_Iterator(Disp_Iterator_Type iterator);
Disp_Iterator_Type Disp_Get_Begin_Iterator();
Disp_Iterator_Type Disp_Get_End_Iterator(Disp_Iterator_Type iterator);

/*!
    @function
    @abstract   MPI Rank
    @discussion Returns the MPI rank within the framwork communication 
    @result     returns MPI rank
*/
int		Disp_Get_Rank();

/*!
 @function
 @abstract   MPI Size
 @discussion Returns the MPI size within the framwork communication 
 @result     returns MPI size
 */
int		Disp_Get_Size();


/*!
	@function
	@abstract   Finalize the Dispatch execution environment
	@discussion Deallocate resources and finalize the execution environment
	@result     Return zero if sucessful
 */
int		Disp_Finalize();

